
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>pypcd &#8212; pypcd 0.1.1 documentation</title>
    <link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript" src="_static/documentation_options.js"></script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Installation" href="installation.html" />
    <link rel="prev" title="Welcome to pypcd’s documentation!" href="index.html" />
   
  <link rel="stylesheet" href="_static/custom.css" type="text/css" />
  
  
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />

  </head><body>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          

          <div class="body" role="main">
            
  <div class="section" id="pypcd">
<h1><code class="docutils literal notranslate"><span class="pre">pypcd</span></code><a class="headerlink" href="#pypcd" title="Permalink to this headline">¶</a></h1>
<a class="reference external image-reference" href="https://travis-ci.com/DanielPollithy/pypcd"><img alt="https://travis-ci.com/DanielPollithy/pypcd.svg?branch=master" src="https://travis-ci.com/DanielPollithy/pypcd.svg?branch=master" /></a>
<div class="section" id="under-construction">
<h2>Under construction<a class="headerlink" href="#under-construction" title="Permalink to this headline">¶</a></h2>
<p>This is a fork of Daniel Maturanas module “pypcd”. Due to its
inactivity I am advancing this repository. The code was merged
with the latest pull requests and I am working on the lost of open todos:</p>
<blockquote>
<div><ul class="simple">
<li>[ ] Better API for various operations.</li>
<li>[ ] Clean up, get rid of cruft.</li>
<li>[ ] Add a cli for common use cases like file type conversion.</li>
<li>[ ] Better support for structured point clouds, with tests.</li>
<li>[ ] Better testing.</li>
<li>[ ] Better docs. More examples.</li>
<li>[ ] More testing of padding</li>
<li>[ ] Improve handling of multicount fields</li>
<li>[ ] Better support for rgb nonsense</li>
<li>[ ] Export to ply?</li>
<li>[x] Fix tox + travis</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="what">
<h2>What?<a class="headerlink" href="#what" title="Permalink to this headline">¶</a></h2>
<p>Pure Python module to read and write point clouds stored in the
<a class="reference external" href="http://pointclouds.org/documentation/tutorials/pcd_file_format.php">PCD file format</a>,
used by the <a class="reference external" href="http://pointclouds.org/">Point Cloud Library</a>.</p>
</div>
<div class="section" id="why">
<h2>Why?<a class="headerlink" href="#why" title="Permalink to this headline">¶</a></h2>
<p>You want to mess around with your point cloud data without writing C++
and waiting hours for the template-heavy PCL code to compile.</p>
<p>You tried to get some of the Python bindings for PCL to compile
and just gave up.</p>
</div>
<div class="section" id="how-does-it-work">
<h2>How does it work?<a class="headerlink" href="#how-does-it-work" title="Permalink to this headline">¶</a></h2>
<p>It parses the PCD header and loads the data (whether in <code class="docutils literal notranslate"><span class="pre">ascii</span></code>,
<code class="docutils literal notranslate"><span class="pre">binary</span></code> or <code class="docutils literal notranslate"><span class="pre">binary_compressed</span></code> format) as a
<a class="reference external" href="http://www.numpy.org">Numpy</a> structured array. It creates an
instance of the <code class="docutils literal notranslate"><span class="pre">PointCloud</span></code>
class, containing the point cloud data as <code class="docutils literal notranslate"><span class="pre">pc_data</span></code>, and
some convenience functions for I/O and metadata access.
See the comments in <code class="docutils literal notranslate"><span class="pre">pypcd.py</span></code> for some info on the point cloud
structure.</p>
</div>
<div class="section" id="example">
<h2>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
<div class="code python highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">pypcd</span>
<span class="c1"># also can read from file handles.</span>
<span class="n">pc</span> <span class="o">=</span> <span class="n">pypcd</span><span class="o">.</span><span class="n">PointCloud</span><span class="o">.</span><span class="n">from_path</span><span class="p">(</span><span class="s1">&#39;foo.pcd&#39;</span><span class="p">)</span>
<span class="c1"># pc.pc_data has the data as a structured array</span>
<span class="c1"># pc.fields, pc.count, etc have the metadata</span>

<span class="c1"># center the x field</span>
<span class="n">pc</span><span class="o">.</span><span class="n">pc_data</span><span class="p">[</span><span class="s1">&#39;x&#39;</span><span class="p">]</span> <span class="o">-=</span> <span class="n">pc</span><span class="o">.</span><span class="n">pc_data</span><span class="p">[</span><span class="s1">&#39;x&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">mean</span><span class="p">()</span>

<span class="c1"># save as binary compressed</span>
<span class="n">pc</span><span class="o">.</span><span class="n">save_pcd</span><span class="p">(</span><span class="s1">&#39;bar.pcd&#39;</span><span class="p">,</span> <span class="n">compression</span><span class="o">=</span><span class="s1">&#39;binary_compressed&#39;</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="how-to-install">
<h2>How to install<a class="headerlink" href="#how-to-install" title="Permalink to this headline">¶</a></h2>
<div class="code bash highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">pypcd</span>
</pre></div>
</div>
<p>That’s it! You may want to install optional dependencies such as <a class="reference external" href="https://pandas.pydata.org">pandas</a>.</p>
<p>You can also clone this repo and use setup.py.</p>
<div class="code bash highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">dimatura</span><span class="o">/</span><span class="n">pypcd</span>
</pre></div>
</div>
<p>Note that downloading data assets will
require <a class="reference external" href="https://git-lfs.github.com">git-lfs</a>.</p>
</div>
<div class="section" id="using-with-ros">
<h2>Using with ROS<a class="headerlink" href="#using-with-ros" title="Permalink to this headline">¶</a></h2>
<p>You can also use this library with ROS <code class="docutils literal notranslate"><span class="pre">sensor_msgs</span></code>, but it is <em>not</em> a dependency.
You don’t need to install this package with catkin – using <cite>pip</cite> should be fine –
but if you want to it is possible:</p>
<p>Steps:</p>
<div class="code bash highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># you need to do this manually in this case</span>
<span class="n">pip</span> <span class="n">install</span> <span class="n">python</span><span class="o">-</span><span class="n">lzf</span>
<span class="n">cd</span> <span class="n">your_workspace</span><span class="o">/</span><span class="n">src</span>
<span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">dimatura</span><span class="o">/</span><span class="n">pypcd</span>
<span class="n">mv</span> <span class="n">setup_ros</span><span class="o">.</span><span class="n">py</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span>
<span class="n">catkin</span> <span class="n">build</span> <span class="n">pypcd</span>
<span class="n">source</span> <span class="o">../</span><span class="n">devel</span><span class="o">/</span><span class="n">setup</span><span class="o">.</span><span class="n">bash</span>
</pre></div>
</div>
<p>Then you can do something like this:</p>
<div class="code python highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">pypcd</span>
<span class="kn">import</span> <span class="nn">rospy</span>
<span class="kn">from</span> <span class="nn">sensor_msgs.msg</span> <span class="k">import</span> <span class="n">PointCloud2</span>


<span class="k">def</span> <span class="nf">cb</span><span class="p">(</span><span class="n">msg</span><span class="p">):</span>
    <span class="n">pc</span> <span class="o">=</span> <span class="n">PointCloud</span><span class="o">.</span><span class="n">from_msg</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>
    <span class="n">pc</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="s1">&#39;foo.pcd&#39;</span><span class="p">,</span> <span class="n">compression</span><span class="o">=</span><span class="s1">&#39;binary_compressed&#39;</span><span class="p">)</span>
    <span class="c1"># maybe manipulate your pointcloud</span>
    <span class="n">pc</span><span class="o">.</span><span class="n">pc_data</span><span class="p">[</span><span class="s1">&#39;x&#39;</span><span class="p">]</span> <span class="o">*=</span> <span class="o">-</span><span class="mi">1</span>
    <span class="n">outmsg</span> <span class="o">=</span> <span class="n">pc</span><span class="o">.</span><span class="n">to_msg</span><span class="p">()</span>
    <span class="c1"># you&#39;ll probably need to set the header</span>
    <span class="n">outmsg</span><span class="o">.</span><span class="n">header</span> <span class="o">=</span> <span class="n">msg</span><span class="o">.</span><span class="n">header</span>
    <span class="n">pub</span><span class="o">.</span><span class="n">publish</span><span class="p">(</span><span class="n">outmsg</span><span class="p">)</span>

<span class="c1"># ...</span>
<span class="n">sub</span> <span class="o">=</span> <span class="n">rospy</span><span class="o">.</span><span class="n">Subscriber</span><span class="p">(</span><span class="s1">&#39;incloud&#39;</span><span class="p">,</span> <span class="n">PointCloud2</span><span class="p">)</span>
<span class="n">pub</span> <span class="o">=</span> <span class="n">rospy</span><span class="o">.</span><span class="n">Publisher</span><span class="p">(</span><span class="s1">&#39;outcloud&#39;</span><span class="p">,</span> <span class="n">PointCloud2</span><span class="p">,</span> <span class="n">cb</span><span class="p">)</span>
<span class="n">rospy</span><span class="o">.</span><span class="n">init</span><span class="p">(</span><span class="s1">&#39;pypcd_node&#39;</span><span class="p">)</span>
<span class="n">rospy</span><span class="o">.</span><span class="n">spin</span><span class="p">()</span>
</pre></div>
</div>
</div>
<div class="section" id="is-it-beautiful-production-ready-code">
<h2>Is it beautiful, production-ready code?<a class="headerlink" href="#is-it-beautiful-production-ready-code" title="Permalink to this headline">¶</a></h2>
<p>No.</p>
</div>
<div class="section" id="what-else-can-it-do">
<h2>What else can it do?<a class="headerlink" href="#what-else-can-it-do" title="Permalink to this headline">¶</a></h2>
<p>There’s a bunch of functionality accumulated
over time, much of it hackish and untested.
In no particular order,</p>
<ul class="simple">
<li>Supports <code class="docutils literal notranslate"><span class="pre">ascii</span></code>, <code class="docutils literal notranslate"><span class="pre">binary</span></code> and <code class="docutils literal notranslate"><span class="pre">binary_compressed</span></code> data.
The latter requires the <code class="docutils literal notranslate"><span class="pre">lzf</span></code> module.</li>
<li>Decode and encode RGB into a single <code class="docutils literal notranslate"><span class="pre">float32</span></code> number. If
you don’t know what I’m talking about consider yourself lucky.</li>
<li>Point clouds to <a class="reference external" href="https://pandas.pydata.org">pandas</a> dataframes.
This in particular is quite useful,
since <cite>pandas</cite> is pretty powerful and makes various operations
such as merging point clouds or manipulating values easy.
Conceptually, data frames are a good match to the point cloud format, since
many point clouds in reality have heterogeneous data types - e.g.
<cite>x</cite>, <cite>y</cite> and <cite>z</cite> are float fields but <cite>label</cite> is an int.</li>
<li>Convert to and from <a class="reference external" href="http://www.ros.org">ROS</a> PointCloud2
messages.
Requires the ROS <code class="docutils literal notranslate"><span class="pre">sensor_msgs</span></code> package with Python bindings
installed.
This functionality uses code developed by Jon Binney under
the BSD license, included as <code class="docutils literal notranslate"><span class="pre">numpy_pc2.py</span></code>.</li>
</ul>
</div>
<div class="section" id="what-can-t-it-do">
<h2>What can’t it do?<a class="headerlink" href="#what-can-t-it-do" title="Permalink to this headline">¶</a></h2>
<p>There’s no synchronization between the metadata fields in
<code class="docutils literal notranslate"><span class="pre">PointCloud</span></code>
and the data in <code class="docutils literal notranslate"><span class="pre">pc_data</span></code>. If you change the shape of <code class="docutils literal notranslate"><span class="pre">pc_data</span></code>
without updating the metadata fields you’ll run into trouble.</p>
<p>I’ve only used it for unorganized point cloud data
(in PCD conventions, <code class="docutils literal notranslate"><span class="pre">height=1</span></code>), not organized
data like what you get from RGBD.
However, some things may still work.</p>
<p>While padding and fields with count larger
than 1 seem to work, this is a somewhat
ad-hoc aspect of the PCD format, so be careful.
If you want to be safe, you’re probably better off
using neither – just name each component
of your field something like <code class="docutils literal notranslate"><span class="pre">FIELD_00</span></code>, <code class="docutils literal notranslate"><span class="pre">FIELD_01</span></code>, etc.</p>
<p>It also can’t run on Python 3, yet, but there’s a PR to fix this
that might get pulled in the near future.</p>
</div>
<div class="section" id="it-s-slow">
<h2>It’s slow!<a class="headerlink" href="#it-s-slow" title="Permalink to this headline">¶</a></h2>
<p>Try using <code class="docutils literal notranslate"><span class="pre">binary</span></code> or <code class="docutils literal notranslate"><span class="pre">binary_compressed</span></code>; using
ASCII is slow and takes up a lot of space, not to
mention possibly inaccurate if you’re not careful
with how you format your floats.</p>
</div>
<div class="section" id="i-found-a-bug-i-added-a-feature-i-made-your-code-cleaner">
<h2>I found a bug / I added a feature / I made your code cleaner<a class="headerlink" href="#i-found-a-bug-i-added-a-feature-i-made-your-code-cleaner" title="Permalink to this headline">¶</a></h2>
<p>Thanks! You can submit a pull request. But honestly, I’m not too good
at keeping up with my github :(</p>
</div>
<div class="section" id="todo">
<h2>TODO<a class="headerlink" href="#todo" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li>Better API for various operations.</li>
<li>Clean up, get rid of cruft.</li>
<li>Add a cli for common use cases like file type conversion.</li>
<li>Better support for structured point clouds, with tests.</li>
<li>Better testing.</li>
<li>Better docs. More examples.</li>
<li>More testing of padding</li>
<li>Improve handling of multicount fields</li>
<li>Better support for rgb nonsense</li>
<li>Export to ply?</li>
<li>Figure out if it’s acceptable to use “pointcloud” as a single word.</li>
<li>Package data assets in pypi?</li>
</ul>
</div>
<div class="section" id="credits">
<h2>Credits<a class="headerlink" href="#credits" title="Permalink to this headline">¶</a></h2>
<p>The code for compressed point cloud data was informed by looking at
<a class="reference external" href="https://www.mathworks.com/matlabcentral/fileexchange/40382-matlab-to-point-cloud-library?requestedDomain=true">Matlab
PCL</a>.</p>
<p>&#64;wkentaro for some minor changes.</p>
<p>I used <a class="reference external" href="https://github.com/audreyr/cookiecutter">cookiecutter</a> to
help with the packaging.</p>
<p>The code in <code class="docutils literal notranslate"><span class="pre">numpy_pc2.py</span></code> was developed by Jon Binney under
the BSD license for <a class="reference external" href="http://www.ros.org">ROS</a>.</p>
</div>
<div class="section" id="i-want-to-congratulate-you-insult-you">
<h2>I want to congratulate you / insult you<a class="headerlink" href="#i-want-to-congratulate-you-insult-you" title="Permalink to this headline">¶</a></h2>
<p>My email is <code class="docutils literal notranslate"><span class="pre">dimatura&#64;cmu.edu</span></code>.</p>
<p>Copyright (C) 2015-2017 Daniel Maturana</p>
</div>
</div>


          </div>
          
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#"><code class="docutils literal notranslate"><span class="pre">pypcd</span></code></a><ul>
<li><a class="reference internal" href="#under-construction">Under construction</a></li>
<li><a class="reference internal" href="#what">What?</a></li>
<li><a class="reference internal" href="#why">Why?</a></li>
<li><a class="reference internal" href="#how-does-it-work">How does it work?</a></li>
<li><a class="reference internal" href="#example">Example</a></li>
<li><a class="reference internal" href="#how-to-install">How to install</a></li>
<li><a class="reference internal" href="#using-with-ros">Using with ROS</a></li>
<li><a class="reference internal" href="#is-it-beautiful-production-ready-code">Is it beautiful, production-ready code?</a></li>
<li><a class="reference internal" href="#what-else-can-it-do">What else can it do?</a></li>
<li><a class="reference internal" href="#what-can-t-it-do">What can’t it do?</a></li>
<li><a class="reference internal" href="#it-s-slow">It’s slow!</a></li>
<li><a class="reference internal" href="#i-found-a-bug-i-added-a-feature-i-made-your-code-cleaner">I found a bug / I added a feature / I made your code cleaner</a></li>
<li><a class="reference internal" href="#todo">TODO</a></li>
<li><a class="reference internal" href="#credits">Credits</a></li>
<li><a class="reference internal" href="#i-want-to-congratulate-you-insult-you">I want to congratulate you / insult you</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
  <li><a href="index.html">Documentation overview</a><ul>
      <li>Previous: <a href="index.html" title="previous chapter">Welcome to pypcd’s documentation!</a></li>
      <li>Next: <a href="installation.html" title="next chapter">Installation</a></li>
  </ul></li>
</ul>
</div>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="_sources/readme.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &copy;2018, Daniel Maturana.
      
      |
      Powered by <a href="http://sphinx-doc.org/">Sphinx 1.7.1</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
      
      |
      <a href="_sources/readme.rst.txt"
          rel="nofollow">Page source</a>
    </div>

    

    
  </body>
</html>